home *** CD-ROM | disk | FTP | other *** search
/ Total Web Page (Professional Suite) / Total Web Page 99.iso / CGI / DOWNLOAD.CGI-S=COOKIELIB&C=TXT&F=README < prev    next >
Text File  |  1996-06-03  |  31KB  |  631 lines
  1. ##############################################################################
  2. # HTTP Cookie Library           Version 2.1                                  #
  3. # Copyright 1996 Matt Wright    mattw@worldwidemart.com                      #
  4. # Created 07/13/96              Last Modified 12/23/96                       #
  5. # Scripts Archive at:           http://www.worldwidemart.com/scripts/        #
  6. # Parts of Code Contributed by Jeff Carnahan (http://terminalp.com/scripts/) #
  7. ##############################################################################
  8. # If you run into any problems while trying to configure this script, help   #
  9. # is available.  The steps you should take to get the fastest results, are:  #
  10. #       1) Read this file thoroughly                                         #
  11. #       2) Consult the Matt's Script Archive Frequently Asked Questions:     #
  12. #               http://www.worldwidemart.com/scripts/faq/                    #
  13. #       3) If you are still having difficulty installing this script, send   #
  14. #          e-mail to: scripts-help@tahoenet.com                              #
  15. #          Include any error messages you are receiving and as much detail   # 
  16. #          as you can so we can spot your problem.  Also include the variable#
  17. #          configuration block that is located at the top of the script.     #
  18. #                                                                            #
  19. # Hopefully we will be able to help you solve your problems.  Thank you.     #
  20. ##############################################################################
  21. # COPYRIGHT NOTICE                                                           #
  22. # Copyright 1996 Matthew M. Wright  All Rights Reserved.                     #
  23. #                                                                            #
  24. # HTTP Cookie Library may be used and modified free of charge by anyone so   #
  25. # long as this copyright notice and the comments above remain intact.  By    #
  26. # using this code you agree to indemnify Matthew M. Wright from any          #
  27. # liability that might arise from it's use.                                  #  
  28. #                                                                            #
  29. # Selling the code for this program without prior written consent is         #
  30. # expressly forbidden.  In other words, please ask first before you try and  #
  31. # make money off of my program.                                              #
  32. #                                                                            #
  33. # Obtain permission before redistributing this software over the Internet or #
  34. # in any other medium.  In all cases copyright and header must remain intact #
  35. ##############################################################################
  36.  
  37. TABLE OF CONTENTS:
  38. ==================
  39.  
  40. 1) Overview
  41. 2) cookie.lib Configuration
  42.     a) $Cookie_Exp_Date
  43.     b) $Cookie_Path
  44.     c) $Cookie_Domain
  45.     d) $Secure_Cookie
  46.     e) @Cookie_Encode_Chars
  47.     f) %Cookie_Encode_Chars
  48.     g) @Cookie_Decode_Chars
  49.     h) %Cookie_Decode_Chars
  50. 3) Using this Library in your CGI script.
  51.     a) Requiring the library.
  52.     b) Subroutine calls.
  53.         + &GetCookies
  54.         + &SetCookieExpDate
  55.         + &SetCookiePath
  56.         + &SetCookieDomain
  57.         + &SetSecureCookie
  58.         + &SetCookies
  59.         + &SetCompressedCookies
  60.         + &GetCompressedCookies
  61. 4) Character Translation Information
  62. 5) Any Examples Available?
  63.     a) ccounter.pl
  64.     b) Scripts Around the World
  65. 6) Other Cookie Resources
  66. 7) History
  67.  
  68. ##############################################################################
  69.  
  70.                                    OVERVIEW
  71.                                    ========
  72.  
  73. HTTP Cookie Library is a Perl 4 and 5 compatible library which allows you to 
  74. easily use Persistent Client State HTTP Cookies by allowing you to get the 
  75. cookies from the environment, prepare cookies, set cookies, change the 
  76. expiration date, domain and path all with easy subroutine calls.
  77.  
  78. Version 2.0 and 2.1 contain many changes, including the ability to compress
  79. multiple cookies into one, the elimination of the &PrepareCookies subroutine,
  80. and fixes allowing you to set more than one cookie at a time.  The addition of
  81. character URL-encoding and the fixing of a scoping bug brought on by 
  82. localizing the global variables used in this script are new to version 2.1.
  83.  
  84. NOTE: Anyone who used 2.0 and &UnCompressCookies should now change all
  85.       references from &UnCompressCookies to &GetCompressedCookies.  The calls
  86.       to these routines are the same, however the name has been changed.
  87.  
  88. For more information on Cookies, and to see the preliminary specifications
  89. of Persistent Client State HTTP Cookies to which this library conforms, visit
  90. http://www.netscape.com/newsref/std/cookie_spec.html
  91.  
  92. There are three files included with this script:
  93.         1) README       - This file; includes detailed installation 
  94.                           instructions.
  95.         2) cookie.lib   - The Perl script which generates the random phrase
  96.                           and displays it on your web page.
  97.         3) ccounter.pl  - An example of how to use this library.
  98.  
  99. The cookie.lib perl library is not a stand-alone CGI script.  It is meant to
  100. be used in conjunction with a script that you build.  It's only purpose is to
  101. facilitate the usage of client side persistent HTTP cookies.  This means, in 
  102. order to use this library, you should always have the following line in your
  103. script somewhere:
  104.  
  105.     require '/path/to/cookie.lib';
  106.  
  107. This will then tell Perl to retrieve this file and include it's code and 
  108. subroutines in your script.  Nonetheless, there are some variables which you
  109. can modify in the cookie.lib file before you place it on your system.  All
  110. of these variables can be modified through special subroutines in cookie.lib
  111. so it is not necessary to edit any of them.
  112.  
  113. ##############################################################################
  114.  
  115.                            COOKIE.LIB CONFIGURATION
  116.                            ========================
  117.  
  118. This program contains three variables which can be modified in the library, to
  119. make it easier to use on your system.  They can also be set through calling
  120. subroutines, which is explained in: 'Using this Library in Your CGI Script,'
  121. or by setting them in your main script, as they are local variables which can
  122. be modified.  The subroutines provide checks to make sure the value is valid.
  123.  
  124.       $Cookie_Exp_Date = '';
  125.             This variable defines the expiration date of your cookie.
  126.             When this date arrives the browser will ask the user if
  127.             they want to delete the cookie, and that it is ok to do so.
  128.             This date must always be represented as:
  129.             Wdy, DD-Mon-YYYY HH:MM:SS GMT
  130.             and always has to be in GMT time.  An example would be:
  131.             Wed, 09-Nov-1999 00:00:00 GMT.  By default, if this is
  132.             not filled in, the browser will delete the cookie when the
  133.             session ends.  Also see &SetCookieExpDate.
  134.  
  135.       $Cookie_Path = '';
  136.             This path defines where under your domain the cookies 
  137.             should be sent.  For instance, if your URL is: 
  138.             http://domain.xxx/your_dir/, there is no reason for the 
  139.             browser to send the Cookie header to the base domain name.
  140.             Therefore, you would set this to '/your_dir';  However,
  141.             because this can be set through the script, set it to 
  142.             whatever directory will use this most often or whichever 
  143.             directory you want as default.  If nothing is placed here,
  144.             the default will be assumed to be the script or page which
  145.             created the cookie.  Also see &SetCookiePath.
  146.  
  147.       $Cookie_Domain = '';
  148.             This defines the base domain to which the browse passes the
  149.             cookie.  If you have a domain: www.host.xxx, your.host.xxx
  150.             and host.xxx, which all will use this, you would set this 
  151.             variable to: '.host.xxx';  The following is an excerpt from
  152.             the Netscape Preliminary Specifications of Persistent Client
  153.             State HTTP Cookies:
  154.  
  155.             "Only hosts within the specified domain can set a cookie for 
  156.             a domain and domains must have at least two (2) or three (3)
  157.             periods in them to prevent domains of the form: ".com", 
  158.             ".edu", and "va.us". Any domain that fails within one of the
  159.             seven special top level domains listed below only require 
  160.             two periods. Any other domain requires at least three. The 
  161.             seven special top level domains are: "COM", "EDU", "NET",
  162.             "ORG", "GOV", "MIL", and "INT"."
  163.  
  164.             Also see &SetCookieDomain.
  165.  
  166.       $Secure_Cookie = '0';
  167.             This defines whether or not you want to restrict the 
  168.             transmission of the cookie to a secure server.  If this flag
  169.             is set to '1', by default the cookies you create will only be
  170.             sent to secure servers by the client.  This can also be 
  171.             changed through &SetSecureCookie.
  172.  
  173.       @Cookie_Encode_Chars = ('\%', '\+', '\;', '\,', '\=', '\&', '\:\:', '\s');
  174.             This defines the order in which the special characters should
  175.             be encoded.  More info can be found in section entitled
  176.             'Character Translation Information'.
  177.  
  178.       %Cookie_Encode_Chars = ('\%',   '%25',
  179.                               '\+',   '%2B',
  180.                               '\;',   '%3B',
  181.                               '\,',   '%2C',
  182.                               '\=',   '%3D',
  183.                               '\&',   '%26',
  184.                               '\:\:', '%3A%3A',
  185.                               '\s',   '+');
  186.             This associative array defines the characters to be
  187.             translated as the keys, which can be referred to as:
  188.             $Cookie_Encode_Chars{key} and the values which these
  189.             characters should be translated into.  More info can
  190.             be found in section entitled 'Character Translation
  191.             Information'.
  192.  
  193.       @Cookie_Decode_Chars = ('\+', '\%3A\%3A', '\%26', '\%3D', '\%2C', '\%3B', '\%2B', '\%25');
  194.             This defines the order in which the special characters should
  195.             be decoded.  More info can be found in section entitled
  196.             'Character Translation Information'.
  197.  
  198.       %Cookie_Decode_Chars = ('\+',       ' ',
  199.                               '\%3A\%3A', '::',
  200.                               '\%26',     '&',
  201.                               '\%3D',     '=',
  202.                               '\%2C',     ',',
  203.                               '\%3B',     ';',
  204.                               '\%2B',     '+',
  205.                               '\%25',     '%');
  206.             This associative array defines the characters to be
  207.             translated as the keys, which can be referred to as:
  208.             $Cookie_Decode_Chars{key} and the values which these
  209.             characters should be decoded into.  More info can be
  210.             found in section entitled 'Character Translation
  211.             Information'.
  212.  
  213.  
  214. ##############################################################################
  215.  
  216.                     USING THIS LIBRARY IN YOUR CGI SCRIPT.
  217.                     ======================================
  218.  
  219. HTTP Cookie Library is not meant as a standalone CGI script.  It must be used
  220. in conjunction with other scripts you have written, and provides a basic
  221. outline and easy subroutines which makes implementing the cookies into your
  222. perl program easy.
  223.  
  224. Also, to give cookies to the user, the browser must be pointed to the CGI
  225. application or the CGI application must be imbedded in the HTML document
  226. through Server Side Includes or other technology, such as JavaScript.  If
  227. you choose the JavaScript path, some browsers which support cookies won't
  228. be able to receive them and JavaScript users have no use for this library
  229. as it is only compatible in Perl scripted CGI applications.
  230.  
  231. Requiring the Library:
  232. ----------------------
  233.  
  234. Near the top of your Perl CGI script (or before you make the first call to a
  235. subroutine which is in cookie.lib), you will need to include the line:
  236.  
  237. require '/path/to/cookie.lib';
  238.  
  239. If you place the cookie.lib in the same directory as your CGI script, or in
  240. a path which is defined in @INC, you can call it with:
  241.  
  242. require 'cookie.lib';
  243.  
  244. Now all of the subroutines which this script contains can be used in your CGI
  245. Perl script.  Here's is a summary of them, what they do and how to call them:
  246.  
  247. Subroutine Calls:
  248. -----------------
  249.  
  250. &GetCookies('cookie_name1',...,'cookie_namen');
  251.       This function can be called as simply &GetCookies, or using arguments
  252.       such as &GetCookies('cookie1','cookie2').  Calling it without
  253.       arguments means that it will return a '1' if cookies are found, a 0
  254.       if they are not.  This is useful, so that you can perform function 
  255.       like:
  256.  
  257.             if (&GetCookies) {
  258.                 # Successful Code Here;
  259.             }
  260.             else {
  261.                 # Give them a Cookie Here;
  262.             }
  263.  
  264.       In the above circumstance, if cookies are found, the successful code
  265.       gets executed.  Otherwise, you can give them a cookie.  The 
  266.       &GetCookies subroutine then takes the cookies from the environment
  267.       and places them in an associative array.  This array is %Cookies.
  268.       So if you have set a cookie named 'visit' with a value which contains
  269.       whatever you set it for, then you would obtain this value by using
  270.       the scalar variable $Cookies{'visit'}.
  271.  
  272.       Now, let's say that a lot of cookies are set for your base domain and
  273.       path.  They would all get included in the return if you didn't
  274.       specify arguments for &GetCookies.  For instance, in the above 
  275.       example, since &GetCookies would return a value of '1' if any cookies
  276.       are set, that could mess up this script, if all we want to know is if
  277.       the visit cookie is set.  Therefore, we would change the above program
  278.       to only need to 'visit' cookie:
  279.  
  280.         if (&GetCookies('visit')) {
  281.                 # Successful Code Here;
  282.         }
  283.             else {
  284.                 # Give them a Cookie Here;
  285.             }
  286.  
  287.       Now, only the $Cookies{'visit'} scalar will be set and if it is not
  288.       &GetCookies will return a 0 and the else { } statement will be 
  289.       executed.
  290.  
  291.       You can check for multiple cookies to be set by &GetCookies('name1',
  292.       'name2','etc...');  However this will return a true value (1) if any
  293.       of those cookies are set.  You can get around this by calling them one
  294.       at a time, although this is tedious.
  295.  
  296.       If you have compressed your cookies with &SetCompressedCookies, you
  297.       will need to look into the &GetCompressedCookies routine to do what
  298.       &GetCookies does.
  299.  
  300. &SetCookieExpDate('Wdy, DD-Mon-YYYY HH:MM:SS GMT');
  301.  
  302.     By default in the script, the cookie is set to expire when the browser
  303.       session ends.  If    you wish for the cookie to expire at a later date,
  304.       then all you have to do is change the date by calling &SetCookieExpDate
  305.       with an argument containing the new date.  The new date must be in the
  306.       format as shown above, or it will not set right. The following is an
  307.       example:
  308.  
  309.     &SetCookieExpDate('Wed, 09-Nov-1999 00:00:00 GMT');
  310.  
  311.     If your date does not match a regular expression which checks to see
  312.     if it is valid, it will return a 0.  So it you catch the value, you
  313.     can do:
  314.  
  315.         if (&SetCookieExpDate('Wdy, DD-Mon-YYYY HH:MM:SS GMT')) {
  316.             # Continue here.
  317.         }
  318.         else {
  319.             # Do Error Stuff Here.  &SetCookieExpDate failed.
  320.         }
  321.  
  322.     For any cookies which you wish to be able to detect if the user closes
  323.       the browser's session and then re-opens it, you will need to set this
  324.       to a specific date.
  325.  
  326.       The $Cookie_Exp_Date variable can also be changed at the top of
  327.       cookie.lib, or at any point inside of the perl script which required
  328.       cookie.lib, simply with the statement: 
  329.       $Cookie_Exp_Date = 'Wdy, DD-Mon-YYYY HH:MM:SS GMT';
  330.       The subroutine is provided to check the syntax of your date.
  331.  
  332. &SetCookiePath('/path');
  333.  
  334.     By default, this is set to the path of the script or web page which sets
  335.       the cookie, so unless this has been set differently in cookie.lib to
  336.       contain a value, you need not call this function.  However, if you wish
  337.       for those values to be passed to other scripts under the same domain,
  338.     you will need to have this set to that path of the URL.  For 
  339.     instance, if I only want my cookies passed to URLs which are at least:
  340.     http://www.worldwidemart.com/scripts, I would call this function as:
  341.  
  342.         &SetCookiePath('/scripts');
  343.  
  344.       You can also set the cookie path with the statement:
  345.       $Cookie_Path = '/path/you/want/to/set';
  346.       You can place this statement anywhere in your Perl programs after you
  347.       have required the cookie.lib library.
  348.  
  349. &SetCookieDomain('.host.xxx');
  350.  
  351.       If the value of your desired domain suffix (.host.xxx) was assigned    
  352.     a different value as default, you can change this by placing a domain
  353.       name in the call to &SetCookieDomain.  Most of the time you shouldn't
  354.     have to worry about this.  Below are the rules which this script
  355.       follows, taken directly from Netscape documentation:
  356.  
  357.             "Only hosts within the specified domain can set a cookie for 
  358.             a domain and domains must have at least two (2) or three (3)
  359.             periods in them to prevent domains of the form: ".com", 
  360.             ".edu", and "va.us". Any domain that fails within one of the
  361.             seven special top level domains listed below only require 
  362.             two periods. Any other domain requires at least three. The 
  363.             seven special top level domains are: "COM", "EDU", "NET",
  364.             "ORG", "GOV", "MIL", and "INT"."
  365.  
  366.       The $Cookie_Domain can also be set using the statemement:
  367.       $Cookie_Domain = 'host.xxx';
  368.       You can place this statement anywhere in your Perl programs after you
  369.       have required the cookie.lib library.
  370.  
  371. &SetSecureCookie('0' || '1');
  372.  
  373.       This defines whether or not this cookie should be relayed only to 
  374.       secure servers.  Calling &SetSecureCookie('1'); means that clients 
  375.       will only pass those cookies you have set to secure servers.  
  376.       Calling &SetSecureCookie('0'); means the cookies will be transferred
  377.       whenever the path and domain are correct, regardless of security issues.
  378.       Here is an excerpt from Netscape specs:
  379.  
  380.             "If a cookie is marked secure, it will only be transmitted if the
  381.             communications channel with the host is a secure one. Currently
  382.             this means that secure cookies will only be sent to HTTPS (HTTP
  383.             over SSL) servers.  If secure is not specified, a cookie is 
  384.             considered safe to be sent in the clear over unsecured channels."
  385.  
  386.       You can also change the value of $Secure_Cookie through a statement:
  387.       $Secure_Cookie = 1;        or        $Secure_Cookie = 0;
  388.       You can place this statement anywhere in your Perl programs after you
  389.       have required the cookie.lib library.
  390.  
  391. &SetCookies('cookie_name1','cookie_value1',...,'cookie_namen','cookie_valuen');
  392.       This function has been completely changed since Version 1.1.1, except
  393.       for the fact that it actually does set the cookies.  There is no longer
  394.       a call to &PrepareCookies, but rather &SetCookies does it all.
  395.  
  396.       If you wish to set the cookies name and email, and have the values of
  397.       these cookies in the variables $name and $email, you would set them with
  398.       the following code:
  399.  
  400.             print "Content-type: text/html\n";
  401.             &SetCookies('name',"$name",'email',"$email");
  402.             print "\n";
  403.  
  404.       The first line prints out the text/html header, with one new line
  405.       following it, rather than two, since the header sent to the browser is
  406.       not yet complete.  Then, our call to &SetCookies is made.  This call
  407.       will send two Set-Cookie: headers to the browser and set both of the
  408.       cookies for us.
  409.  
  410.       You can send as many cookies to this subroutine as you wish to set.  
  411.       Browsers do have a limit though, so if you are setting multiple
  412.       cookies, it is suggested that you look into the &SetCompressedCookies
  413.       subroutine.
  414.  
  415. &SetCompressedCookies('compressed_cookie_name','cookie_name1','cookie_value1',
  416.                       ...,'cookie_namen','cookie_valuen');
  417.  
  418.       This subroutine does almost the same thing that &SetCookies does, but
  419.       instead it takes one extra argument.  You call it with the name of the
  420.       compressed cookie which you wish to set and then the name/value pairs of
  421.       of the cookies which you wish to compress.  This subroutine doesn't
  422.       actually compress cookies, but it takes multiple cookies and strings
  423.       them together, so to the browser they appear as one.  The = signs are
  424.       converted into :: and the name/value pairs are separated from each other
  425.       by &, however there is no need to change these characters before hand,
  426.       as they will be translated back when uncompressed.
  427.  
  428.       You may be saying, why should I bother compressing cookies when it takes
  429.       extra work?  I can just set 50 cookies all for different things.  The
  430.       main reason is, that according to Netscape's specification:
  431.  
  432.             "There are limitations on the number of cookies that a client can 
  433.             store at any one time. This is a specification of the minimum 
  434.             number of cookies that a client should be prepared to receive and
  435.             store. 
  436.  
  437.                -- 300 total cookies 
  438.                -- 4 kilobytes per cookie, where the name and the value combine
  439.                   to form the 4 kilobyte limit. 
  440.                -- 20 cookies per server or domain. (note that completely 
  441.                   specified hosts and domains are treated as separate entities
  442.                   and have a 20 cookie limitation for each, not combined)
  443.  
  444.             Servers should not expect clients to be able to exceed these 
  445.             limits. When the 300 cookie limit or the 20 cookie per server 
  446.             limit is exceeded, clients should delete the least recently used
  447.             cookie. When a cookie larger than 4 kilobytes is encountered the
  448.             cookie should be trimmed to fit, but the name should remain intact
  449.             as long as it is less than 4 kilobytes."
  450.  
  451.       This also means that it is up to you to check and make sure that your
  452.       compressed cookie will not take more than 4KB.  This is not going to be
  453.       a common problem most likely, though, as 4KB is 4,000 characters, which
  454.       if typed out on a common 80 column screen is about 50 lines, or almost
  455.       a full page of text.  The 20 cookie limit on one server name is
  456.       definitely a common problem, and this helps save some of this space.
  457.       As cookies become more common, clients may start reaching the 300
  458.       cookie maximum more rapidly as well.
  459.  
  460.       Let's take the example from &SetCookies above, with the name and email
  461.       cookies we wish to set.  Now, rather than taking up two cookies, we
  462.       can set one cookie named user, which will contain the information
  463.       stored in the name and email cookies.  To do this, make you make a call
  464.       like:
  465.  
  466.            print "Content-type: text/html\n";
  467.            &SetCompressedCookies('user','name',$name,'email',$email);
  468.            print "\n";
  469.  
  470.       This sets a cookie named user which contains the cookies name and email.
  471.       In order to uncompress this cookie, you need to use the
  472.       &GetCompressedCookies subroutine explained below.  It acts much like
  473.       &GetCookies.
  474.  
  475.       WARNING:  It is a good idea not to set the compressed cookie name equal
  476.                 to the name of a cookie being stored in the compressed cookie.
  477.                 It can mess things up.
  478.  
  479. &GetCompressedCookies('compressed_cookie_name','cookie_name1',...,'cookie_namen');
  480.  
  481.       This subroutine works in almost the same way as &GetCookies, except that
  482.       it needs the name of the compressed cookie first, followed by the names
  483.       of the cookies you wish to retrieve out of the compressed cookie.  If
  484.       this subroutine is called with only the name of the compressed cookie,
  485.       it will retrieve all values and place them in the %Cookies array.
  486.  
  487.       For instance, if we were to take the example used in 
  488.       &SetCompressedCookies and we needed to only get the name of the user out
  489.       of the compressed cookie, we would do something like:
  490.  
  491.       &GetCompressedCookies('user','name');
  492.  
  493.       Where 'user' was the name of the cookie we specified to be set when we
  494.       compressed the cookies and 'name' was one of the cookies we compressed
  495.       into 'user'.  The value of name can not be retrieved from 
  496.       $Cookies{'name'}.
  497.  
  498.       Or if you wished to get every cookie out of the compressed cookie, you
  499.       can simply say:
  500.  
  501.       &GetCompressedCookies('user');
  502.  
  503.       And now $Cookies{'name'} and $Cookies{'email'} are set.
  504.  
  505. ##############################################################################
  506.  
  507.                        CHARACTER TRANSLATION INFORMATION
  508.                        =================================
  509.  
  510. Version 2.1 of the HTTP Cookie Library introduces some simple character
  511. URL-encoding which eases the use and fixes some common problems with cookies.
  512. Previously, cookies would often not be set if they included spaces, semi-
  513. colons, and a few other special characters.  There was also the problem found
  514. if information contained two :: or an & and you tried to compress the cookies,
  515. because those two characters are used for the compression sequence that HTTP
  516. Cookie Library uses.
  517.  
  518. According to Netscape's Persistent Client State HTTP Specification:
  519.  
  520.       "This string is a sequence of characters excluding semi-colon, comma
  521.        and white space. If there is a need to place such data in the name
  522.        or value, some encoding method such as URL style %XX encoding is 
  523.        recommended, though no encoding is defined or required."
  524.  
  525. HTTP Cookie Library does use the URL style %XX (also known as hex) encoding to
  526. ensure that these characters are not lost and that the cookie is set.
  527.  
  528. ##############################################################################
  529.  
  530.                             ANY EXAMPLES AVAILABLE?                           
  531.                             =======================
  532.  
  533. ccounter.pl
  534. -----------
  535.  
  536.       ccounter.pl, an example of how to use some of the features in this
  537.       library comes bundled with the script.  Hopefully the docs have been
  538.       written extensively enough and the library commented enough (this is
  539.       the most commented and well-documented script at MSA) that it should
  540.       be fairly easy to figure out.
  541.  
  542. Scripts Around the World
  543. ------------------------
  544.  
  545.       You can find real-world implementations of this library listed at MSA
  546.       in the Scripts Around the World section.  The HTTP Cookie Library page
  547.       for this can be found at:
  548.  
  549.           http://www.worldwidemart.com/scripts/examples/cookielib.shtml
  550.  
  551.       If you have used the library, please let us know so we can add it!
  552.  
  553. ##############################################################################
  554.  
  555.                             OTHER COOKIE RESOURCES
  556.                             ======================
  557.  
  558. There are many other cookie resources available on the Internet.  Below are
  559. just a few that are the most useful and should help you out.  Enjoy.
  560.  
  561. Netscape Persistent Client State HTTP Cookies Specification
  562.       http://www.netscape.com/newsref/std/cookie_spec.html
  563.       The specifications to which this library conforms.  Contains a lot of
  564.       useful information on Cookies in general and how they can be used.
  565.  
  566. Andy's Netscape HTTP Cookie Info
  567.       http://www.illuminatus.com/cookie.fcgi
  568.       A lot of information on cookies, the security of them, Frequently Asked
  569.       Questions and much more.  A LOT of cookie information. :-)
  570.  
  571. Malcolm's Guide to Persistent Cookies
  572.       http://www.emf.net/~mal/cookiesinfo.html
  573.       This guide to Persistant Cookies explains what cookies are, discusses
  574.       security and privacy issues, gives URLS to more documentation and shows
  575.       some examples of places using cookies.
  576.  
  577. Javascript Cookie Functions
  578.       http://www.hidaho.com/cookies/cookie.txt
  579.       A library much like this one with different subroutines, only
  580.       implemented in JavaScript.
  581.  
  582. HTTP State Management Mechanism RFC
  583.       http://portal.research.bell-labs.com/~dmk/cookie-2.36.txt
  584.       Looks very cookie-related.  Maybe I should start conforming to this.
  585.  
  586. ##############################################################################
  587.  
  588. HISTORY
  589.  
  590.    Version 2.1   - 12/19/96     - Changed the local() scope of global
  591.                                   variables because they weren't setting at
  592.                                   the top of the script right.
  593.                  - 12/20/96     - Added URL-encoding to the cookies for the
  594.                                   characters: '%', '+', ':', ',', '=', '&',
  595.                                   '::', and space.  More on this explained
  596.                                   in the section, 'Character Translation'.
  597.                                 - &UnCompressCookies changed to
  598.                                   &GetCompressedCookies, making more sense.
  599.                  - 12/23/96     - &SetCookieExpDate fixed to allow a blank
  600.                                   date.
  601.    Version 2.0   - 11/28/96     - &SetCookieExpDate still not working right,
  602.                                   and finall fixed.
  603.                                 - &SetCompressedCookies and &UnCompressCookies
  604.                                   subroutines added so multiple cookies can be
  605.                                   set as one cookie and take up less room in
  606.                                   the cookies.txt file.
  607.                                 - &PrepareCookie replaced by changing
  608.                                   &SetCookies to do all of the work.  This
  609.                                   subroutine now actually takes values and
  610.                                   sets them.
  611.                                 - Multiple cookied can be set now.  A bug
  612.                                   existed before which wouldn't set all of
  613.                                   the cookies.
  614.                                 - Checking now done when setting cookie domain
  615.                                   so you can know if it will work.  Based on
  616.                                   information in Netscape's Specifications.
  617.    Version 1.1.1 - 07/15/96     - Andy Kington <andyk@teleport.com> 
  618.                                   pointed out that the ExpDate Year should be
  619.                                   represented as YYYY instead of YY.
  620.    Version 1.1   - 07/14/96     - Added secure option and routines.
  621.    Version 1.0   - 07/14/96     - First Version Released
  622.  
  623. ##############################################################################
  624.  
  625. Have fun with this script, but if you can, please, please let me know the URL
  626. of where it is implemented so I can see my work in action (and add you to the
  627. list of sites using this script.)
  628.  
  629. ##############################################################################
  630. Matt Wright - mattw@worldwidemart.com  http://www.worldwidemart.com/scripts/
  631.